home *** CD-ROM | disk | FTP | other *** search
/ System Booster / System Booster.iso / Commodities / SwitchWindow / SwitchWindow.doc < prev    next >
Text File  |  1996-09-26  |  14KB  |  330 lines
  1. ===================== SwitchWindow 0.8 main documentation =================
  2. ===========================================================================
  3. A  simple  window  tool  as  a replacement for  CBM IHelp  to be used  with
  4.  Kickstart 2.x/3.x, written by  Roland 'Gizzy' Mainz,  freeware, all rights
  5.  reserved.
  6. No guarantee of any kind is made  that  the program described below in this
  7.  document is 100% reliable. You use this material on your own risk.
  8.  
  9.  
  10. ============================== Misc =======================================
  11. ===========================================================================
  12. Because  I  don't like  IHelp (one of us  makes  everytime  a mistake)  and
  13.  (at first) I need  the ZOOM gadget very often,  I've programmed   a simple
  14.  tool called 'SwitchWindow'. It only  changes  the  Window's size  via  the
  15.  ZipWindow() call.  Later some other very useful functions were added  (see
  16.  below).
  17.  
  18.  
  19. =========================== Installation ==================================
  20. ===========================================================================
  21. Workbench: Drop the 'SwitchWindow' icon in your favorite drawer (like
  22.  Sys:WBStartup/ or Sys:Tools/Commodities/). Be sure that the tooltype
  23.  DONOTWAIT is set, otherwise the Workbench will call with a requester
  24.  (only WBStartup).
  25.  
  26. CLI/Shell: Drop/Copy the 'SwitchWindow' file in your favorite directory
  27.  (like Sys:Tools/Commodities/).
  28.  If you like to run the program at startup, get your favorite editor
  29.  and add this line to S:user-startup (NOT Startup-Sequence !!):
  30.  run >nil: <nil: Sys:Tools/Commodities/SwitchWindow
  31.  
  32.  
  33. =============================== Usage =====================================
  34. ===========================================================================
  35.  
  36. SwitchWindow may be controlled through three different ways:
  37.   COMMODITIES EXCHANGE
  38.     (Show/Hide)            (not implemented)
  39.     Enable/Disable         activate/deactivate the tool
  40.                            if the tool is deactivated, you couldn't use any
  41.                            function
  42.     Kill                   quits the tool/end
  43.  
  44.   CLI/Shell
  45.     break <process> C      quits the tool/end
  46.     break <process> E      enables the tool in the Commodities Network
  47.     break <process> F      disables it
  48.  
  49.   REXX (global commands)
  50.     'QUIT'                 quits the tool
  51.     'CX_DISABLED=FALSE'    enables the tool
  52.     'CX_DISABLED=TRUE'     disables the tool
  53.     ('ENABLE'/'DISABLE')   FUTURE commands (>V0.85)
  54.  
  55.   REXX (one hotkey)
  56.     '<command>KEY=enable'  enables one hotkey
  57.                            ('MOVELEFTKEY=enable')
  58.     '<command>KEY=disable' disable one hotkey
  59.                            ('MOVELEFTKEY=disable')
  60.     '<command>KEY=alt x>'  assign the function <command> to the hotkey
  61.                            "alt x"
  62.                            ('MOVELEFTKEY=alt x')
  63.  
  64.     SEE ALSO
  65.       SwitchWindow.rexx.doc
  66.  
  67. The next two points are only valid if you don't set the QUIET
  68.  tooltype/flag:
  69. -If you start a second SwitchWindow, the old one will present you
  70.   a requester:
  71.     Ignore   = put away this ugly requester; do nothing
  72.     Disable  = disable this task in the commodities list
  73.                (like the DISABLE function in COMMODITIES EXCHANGE)
  74.     Kill     = quit the tool
  75. -If you want to quit the SwitchWindow tool it will bring up
  76.   a 'Are you sure ?' requester.
  77. -If a hotkey description is wrong, SwitchWindow will popup a requester
  78.  (V0.85):
  79.     Retry    (V0.85) = Retry to insert the hotkey in the CX network
  80.     Cancel   = abort
  81.  
  82.  
  83. ===================== ToolTypes / Shell arguments =========================
  84. ===========================================================================
  85. There  are  a  number  of  command  line  switches   available  which  also
  86.  correspond  to tooltype  entries  to  be  changed/created by selecting the
  87.  appropriate icon and choosing the Workbench menu item `Icons/Information'.
  88.  
  89. TEMPLATE
  90.   CX_PRIORITY/K/N,CX_NAME/K,CX_TITLE/K,CX_DESCR=CX_DESCRIPTION/K,
  91.   CX_DISABLED/K,QUIET/K,PORTNAME=RXPORTNAME/K,PORTPRI=RXPORTPRI/K/N,
  92.   MOVESTEP/K/N,SIZESTEP/K/N,ZIPWINDOWKEY/K,MAKESMALLKEY/K,MAKEBIGKEY/K,
  93.   CLIPTOWINDOWKEY/K,WINDOWTOCLIPKEY/K,MOVEUPKEY/K,MOVEDOWNKEY/K,
  94.   MOVELEFTKEY/K,MOVERIGHTKEY/K,SIZEUPKEY/K,SIZEDOWNKEY/K,SIZELEFTKEY/K,
  95.   SIZERIGHTKEY/K,PAGEUPKEY/K,PAGEDOWNKEY/K,SIZEPAGEUPKEY/K,
  96.   SIZEPAGEDOWNKEY/K,WINDOWTOMOUSEKEY/K,WINDOWTOFRONTKEY/K,
  97.   WINDOWTOBACKKEY/K,DEBUGWINDOWKEY/K,IGNORESIZEFLAG/K
  98.  
  99.  
  100. CX_PRIORITY/N.... The  Cx priority to assign this tool to.  You may want to
  101.                   change  this  value  if  there is more than one Commodity
  102.                   tool    running   to   use  the  same  key  sequences  as
  103.                   `SwitchWindow'. The one  which  has  the  higher priority
  104.                   will receive the keystrokes first.
  105.                   example: 'CX_PRIORITY=0' (DEFAULT)
  106.  
  107. CX_DISABLED/K.... This is a boolean switch which determines whether
  108.                   SwitchWindow's hotkeys are disabled on startup or not.
  109.                   example: 'CX_DISABLED'
  110.  
  111. CX_NAME/K........ The name string in the Commodities list.
  112.                   example: 'CX_NAME=Yeeha'
  113.  
  114. CX_TITLE......... The title string shown in the CX EXCHANGE window.
  115.                   example: 'CX_TITLE=SwitchWindow'
  116.  
  117. CX_DESCR=
  118. CX_DESCRIPTION/K. The description string shown in the CX EXCHANGE window.
  119.                   example: 'CX_DESCRIPTION=Small tool'
  120.  
  121. PORTNAME=
  122. RXPORTNAME/K..... The REXX port name.
  123.                   example: 'RXPORTNAME=SWrexx'
  124.  
  125. PORTPRI=
  126. RXPORTPRI/K/N.... The REXX port priority.
  127.                   example: 'RXPORTPRI=5'
  128.  
  129. QUIET/K.......... This is a boolean switch which determines whether
  130.                   SwitchWindow pops up a requester or not.
  131.                   SwitchWindow will quit quiet. If another SwitchWindow
  132.                   was started the 'old' SwitchWindow will be removed.
  133.                   example: 'QUIET'
  134.  
  135. ZIPWINDOWKEY/K... 'zip' the window. This function is similar to the
  136.                   window's 'ZOOM'-gadget.
  137.                   example: 'ZIPWINDOWKEY=lcommand z' (DEFAULT)
  138.  
  139. MAKESMALLKEY/K... Makes the window as small as possible.
  140.                   example: 'MAKESMALLKEY=lcommand tab' (DEFAULT)
  141.  
  142. MAKEBIGKEY/K..... Makes the window as big as possible.
  143.                   example: 'MAKEBIGKEY=shift lcommand tab' (DEFAULT)
  144.  
  145. CLIPTOWINDOWKEY/K Moves the visible part of a draggable screen to the
  146.                   window's position.
  147.                   example: 'CLIPTOWINDOWKEY=lcommand w' (DEFAULT)
  148.  
  149. WINDOWTOCLIPKEY/K Changes the window's position to the visible part of
  150.                   the screen (screenclip).
  151.                   example: 'WINDOWTOCLIPKEY=lcommand c' (DEFAULT)
  152.  
  153. MOVEUPKEY/K
  154. MOVEDOWNKEY/K
  155. MOVERIGHTKEY/K
  156. MOVELEFTKEY/K.... The keys to press to move the window in the specified
  157.                   direction.
  158.                   examples:
  159.                     'MOVEUPKEY=lcommand up' (DEFAULT)
  160.                     'MOVEDOWNKEY=lcommand down' (DEFAULT)
  161.                     'MOVERIGHTKEY=lcommand right' (DEFAULT)
  162.                     'MOVELEFTKEY=lcommand left' (DEFAULT)
  163.  
  164. SIZEUPKEY/K
  165. SIZEDOWNKEY/K
  166. SIZERIGHTKEY/K
  167. SIZELEFTKEY/K.... Sizes the window in the specified direction.
  168.                   examples:
  169.                     'SIZEUPKEY=shift lcommand up' (DEFAULT)
  170.                     'SIZEDOWNKEY=shift lcommand down' (DEFAULT)
  171.                     'SIZERIGHTKEY=shift lcommand right' (DEFAULT)
  172.                     'SIZELEFTKEY=shift lcommand left' (DEFAULT)
  173.  
  174. PAGEUPKEY/K
  175. PAGEDOWNKEY/K.... Moves the window up (down) in the window's frame height.
  176.                   examples:'PAGEUPKEY=lcommand numericpad 9' (DEFAULT)
  177.                            'PAGEDOWNKEY=lcommand numericpad 3' (DEFAULT)
  178.  
  179. SIZEPAGEUPKEY/K
  180. SIZEPAGEDOWNKEY/K Size the window up (or down) in the current window's
  181.                   frame height.
  182.                   examples:
  183.                     'SIZEPAGEUPKEY=shift lcommand numericpad 9'
  184.                       (DEFAULT)
  185.                     'SIZEPAGEDOWNKEY=shift lcommand numericpad 3'
  186.                       (DEFAULT)
  187.  
  188. WINDOWTOMOUSEKEY/K Moves the window's left top edge to the mousepointer's
  189.                   position.
  190.                   example: 'WINDOWTOMOUSEKEY=lcommand numericpad 0'
  191.                              (DEFAULT)
  192.  
  193. WINDOWTOFRONTKEY/K Takes the window in front of all other windows in the
  194.                   screen.
  195.                   example: 'WINDOWTOFRONTKEY=lcommand f' (DEFAULT)
  196.  
  197. WINDOWTOBACKKEY/K The keys to press to send the window in back of all
  198.                   other windows in the screen.
  199.                   example: 'WINDOWTOBACKKEY=lcommand b' (DEFAULT)
  200.  
  201. DEBUGWINDOWKEY/K. This creates a system requester with some informations
  202.                   about the window (like name, width, height, leftedge,
  203.                   topedge, ... )
  204.                   example: 'DEBUGWINDOWKEY=lcommand d' (DEFAULT)
  205.  
  206. MOVESTEP/N....... The number of pixels in the screen's resolution to move
  207.                   the window in every direction.
  208.                   example: 'MOVESTEP=20' (DEFAULT)
  209.  
  210. SIZESTEP/N....... The number of pixels in the screen's resolution to size
  211.                   the window in every direction.
  212.                   example: 'SIZESTEP=20' (DEFAULT)
  213.  
  214. IGNORESIZEFLAG/K. If this flag is set, every kind of window will be
  215.                   sized.
  216.  
  217. NOTE(Shell only): Hotkey strings with blanks MUST be enclosed with "...".
  218.    Example: SwitchWindow ZIPWINDOW="shift lcommand z"
  219.  
  220. NOTE: CLIPTOWINDOW and WINDOWTOCLIP will only be useful for
  221.    screens larger than the visible part (here called 'draggable screens')
  222.  
  223. EXAMPLE (from WB / Icon tooltypes)
  224.   DONOTWAIT
  225.   CX_PRIORITY=0
  226.   CX_DISABLED=TRUE
  227.   QUIET
  228.   ZIPWINDOWKEY=lcommand z
  229.   CLIPTOWINDOWKEY=lcommand w
  230.   WINDOWTOCLIPKEY=lcommand c
  231.  
  232.   /* The tool will be loaded with the CX_PRIORITY 0, inactive, no system
  233.      requesters,
  234.      the ZIPWINDOW function will be run through "lcomand z",
  235.          CLIPTOWINDOW                   through "lcommand w" and
  236.          WINDOWTOCLIP                   through "lcommand c".
  237.      The other keys work with their default hotkey strings. */
  238.  
  239. EXAMPLE (from CLI / Shell)
  240.   SwitchWindow CX_PRIORITY=0 CX_DISABLED=TRUE QUIET ZIPWINDOW="lcommand z"
  241.  
  242.   /* The tool will be loaded with the CX_PRIORITY 0, inactive and no
  243.      system requesters.
  244.      The ZIPWINDOW function will be activated through "lcommand z". */
  245.  
  246.  
  247. ======================== About the REXX port ============================
  248. =========================================================================
  249. Since the REXX port documentation is moved into a separate file, I'll
  250. write only a few lines here.
  251. The REXX port implementation is experimental (because I din't get the
  252. AREXX book yet), this means that everything may change !!
  253.  
  254.  
  255. =========================== KNOWN BUGS ==================================
  256. =========================================================================
  257. -DEBUGWINDOW will hang the tool until the requester is closed.
  258. -If one hotkey string is wrong in any kind, SwitchWindow will
  259.    fail without any message (may be removed in V0.85).
  260. -Sometimes the REXX-port will be very slow. Then you may restart the
  261.    tool.
  262. -The REXX port is experimental.
  263. -SIZESTEP & MOVESTEP does not check if their arguments are valid.
  264.    Be careful.
  265. -Today SwitchWindow is only tested on my private AMIGA
  266.  (Amiga 2000C, M68000, 1MB Chip, 8MB Fast, 425MB Nexus HD,
  267.  OS V2.04, EXEC V37.132, COMMODITIES 37.27).
  268.  
  269.  
  270. ============================= TODO ======================================
  271. =========================================================================
  272. -CLIPTOWINDOW/K and WINDOWTOCLIP/K will be enhatched:
  273.        CLIPTOWINDOW=AUTO will run the function with every window's
  274.                          activation.
  275.                          The visible part of the screen will
  276.                          automatically be moved to the active window.
  277.        WINDOWTOCLIP=AUTO will run the function with every window's
  278.                          activation.
  279.                          The window will be moved into the visible
  280.                          part of the screen.
  281. -DEBUGSCREEN/K will create a requester with some informations about
  282.        the Screen.
  283. -If one hotkey string is wrong in any kind, the program will
  284.        pop up a requester (V0.85)
  285. -MAKESMALL may size WB windows in another way (V0.85).
  286. -A special icon for SwitchWindow
  287. -A simple, short manual file (autodoc style)
  288. -AmigaGuide file
  289. -Another REXX port implementation
  290. -locale.library support
  291. -German documentation
  292. -Split up the project in three parts:
  293.        SwitchWindow.rexx.window  (REXX port, window)
  294.        SwitchWindow.rexx         (REXX port, no window) (this distribution)
  295.        SwitchWindow.small        (the pure commodity)
  296.  
  297.  
  298. =========================== Author's Request ==============================
  299. ===========================================================================
  300. By  releasing  this program I do  not  place any obligations on you,
  301. feel free to share this program with your  friends (and enemies).
  302.  
  303. If you want to blame me, report any bugs or want the source,
  304. send your letter to:
  305.                 Roland Mainz
  306.                 Hohenstaufenstraße 8
  307.                 D-5164 Nörvenich
  308.                 GERMANY
  309.  
  310. But, should you feel the need to make any contributions, send them to:
  311.                 Fred Fish
  312.                 Amiga Library Disks
  313.                 1835 East Belmont Drive
  314.                 Tempe, Arizona  85284
  315.                 USA
  316.  
  317. for his great AMIGA library, and his work all over the years.
  318.  
  319.  
  320. The entire  SwitchWindow  package  may  be  noncommercially redistributed,
  321. provided  that  the package  is always  distributed in it's complete  form
  322. (including it's documentation).  A small copy fee  for media costs is okay
  323. but any kind of commercial distribution is strictly forbidden!
  324. Comments  and  suggestions  how  to  improve  this  program  are generally
  325. appreciated!
  326.  
  327. Thanks to Matt Dillon for his DICE, and Olaf 'Olsen' Barthel for his
  328. help, ideas and some text clips from his documentations.
  329.  
  330.